﻿@page "/docs/extensions/treeview"

<Seo Canonical="/docs/extensions/treeview" Title="Blazorise TreeView component" Description="Learn to use and work with the Blazorise TreeView component, a component used to display hierarchical data." />

<DocsPageTitle Path="Extensions/TreeView">
    Blazorise TreeView component
</DocsPageTitle>

<DocsPageLead>
    The <Code>TreeView</Code> component is a graphical control element that presents a hierarchical view of information.
</DocsPageLead>

<DocsPageParagraph>
    The TreeView component is a powerful and flexible way to display hierarchical data in a tree-like structure. It allows users to navigate through the tree and perform actions on the nodes, such as expanding or collapsing them, selecting them, or performing other operations.
</DocsPageParagraph>

<DocsPageSubtitle>
    Features
</DocsPageSubtitle>

<Paragraph>
    <UnorderedList>
        <UnorderedListItem>
            Display hierarchical data in a tree structure.
        </UnorderedListItem>
        <UnorderedListItem>
            Expand or collapse nodes.
        </UnorderedListItem>
        <UnorderedListItem>
            Select single or multiple nodes (depending on the selection mode).
        </UnorderedListItem>
        <UnorderedListItem>
            Allow Node Items to be disabled for selection.
        </UnorderedListItem>
        <UnorderedListItem>
            Customize the appearance of the nodes using templates.
        </UnorderedListItem>
        <UnorderedListItem>
            Perform actions on the nodes, such as deleting them or performing some other operation.
        </UnorderedListItem>
    </UnorderedList>
</Paragraph>

<DocsPageSubtitle>
    Installation
</DocsPageSubtitle>

<DocsPageSection>
    <DocsPageSectionHeader>
        <Paragraph>
            To install the Blazorise TreeView component, run the following command in the Package Manager Console:
        </Paragraph>
    </DocsPageSectionHeader>
    <DocsPageSectionSource Code="TreeViewNugetInstallExample"></DocsPageSectionSource>
    <DocsPageSectionHeader>
        <Paragraph Margin="Margin.Is3.FromTop">
            Alternatively, you can install the package using the .NET Core CLI:
        </Paragraph>
    </DocsPageSectionHeader>
    <DocsPageSectionSource Code="TreeViewNugetInstall2Example"></DocsPageSectionSource>
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Configuration">
        <Paragraph>
            Once the package is installed, you need to configure your Blazor project to use the TreeView component.
        </Paragraph>
        <Paragraph>
            In your main <Badge Color="Color.Light">_Imports.razor</Badge> add:
        </Paragraph>
    </DocsPageSectionHeader>
    <DocsPageSectionSource Code="TreeViewImportsExample"></DocsPageSectionSource>
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Static files">
        Include CSS link into your <Code>index.html</Code> or <Code>_Layout.cshtml</Code> / <Code>_Host.cshtml</Code> file, depending if you’re using a Blazor WebAssembly or Blazor Server side project.
    </DocsPageSectionHeader>
    <DocsPageSectionSource Code="TreeViewResourcesExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Basic example">
        A basic TreeView that aims to reproduce standard tree-view behavior.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <TreeViewExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="TreeViewExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Expanding and Collapsing Nodes">
        By default, all nodes are collapsed except for the root node(s). To expand a node, click on the triangle icon next to its label. To collapse a node, click on the triangle icon again. You can also programmatically expand or collapse nodes using the <Code>ExpandAll()</Code> and <Code>CollapseAll()</Code> property of the TreeView class.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <TreeViewExpandExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="TreeViewExpandExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Multiple selection">
        <Paragraph>
            The TreeView component multiple selection mode, allows users to select multiple nodes at the same time. To enable this mode, set the <Code>SelectionMode</Code> property to <Code>Multiple</Code>. When this mode is enabled, each node in the TreeView will display a checkbox next to its label. Users can then select or deselect nodes by clicking on the checkboxes.
        </Paragraph>
        <Paragraph>
            The selected nodes can be accessed through the <Code>SelectedNodes</Code> property, which returns a list of the selected nodes. You can also use the <Code>SelectedNodesChanged</Code> event to be notified when the selection changes.
        </Paragraph>
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <TreeViewMultiSelectExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="TreeViewMultiSelectExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Observable Lists">
        <Paragraph>
            The Observable Lists feature in Blazorise TreeView component enables automatic updates and synchronization of the TreeView data with the underlying data source. This is achieved through the implementation of an observable pattern where the TreeView component listens to changes in the data source, and updates its visual representation accordingly.
        </Paragraph>
        <Paragraph>
            When using Observable Lists in the Blazorise TreeView component, any modifications to the underlying data source, such as adding, removing, or updating nodes, will automatically trigger the necessary updates in the TreeView component. This ensures that the TreeView always reflects the most up-to-date state of the data.
        </Paragraph>
        <Paragraph>
            It is of note that the <Code>Nodes</Code> parameter is a one way bound collection and as such, if you want to add and remove items, it is recommended that it is used as an <Code>ObservableCollection</Code> in order to keep the TreeView properly synced across refreshes.
        </Paragraph>
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <TreeViewObservableExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="TreeViewObservableExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Node Context Menu">
        <Paragraph>
            To integrate the context menu with the <Strong>TreeView</Strong>, you need to:
        </Paragraph>
        <OrderedList>
            <OrderedListItem>
                <Paragraph>
                    Use the TreeView <Code>NodeContextMenu</Code> event to get the current node and show the menu.
                </Paragraph>
            </OrderedListItem>
            <OrderedListItem>
                <Paragraph>
                    Use the context menu's <Code>MouseEventArgs</Code> parameter to handle the desired operation.
                </Paragraph>
            </OrderedListItem>
        </OrderedList>
        <Paragraph>
            In this example, the context menu is used to show the menu items, put an item in edit mode and delete items.
        </Paragraph>
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <TreeViewContextMenuExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="TreeViewContextMenuExample" />
</DocsPageSection>

<DocsPageSubtitle>
    API
</DocsPageSubtitle>

<Heading Size="HeadingSize.Is3">
    Attributes
</Heading>

<DocsAttributes>
    <DocsAttributesItem Name="Nodes" Type="IEnumerable<TNode>">
        Collection of child TreeView items (child nodes). If null/empty then this node won’t expand.
    </DocsAttributesItem>
    <DocsAttributesItem Name="NodeContent" Type="RenderFragment<TNode>">
        Template to display content for the node.
    </DocsAttributesItem>
    <DocsAttributesItem Name="SelectionMode" Type="TreeViewSelectionMode" Default="Single">
        Defines the selection mode of the TreeView.
    </DocsAttributesItem>
    <DocsAttributesItem Name="SelectedNode" Type="TNode">
        The currently selected TreeView item/node.
    </DocsAttributesItem>
    <DocsAttributesItem Name="SelectedNodeChanged" Type="EventCallback<TNode>">
        Occurs when the selected TreeView node has changed.
    </DocsAttributesItem>
    <DocsAttributesItem Name="SelectedNodes" Type="IList<TNode>">
        The currently selected TreeView items/nodes.
    </DocsAttributesItem>
    <DocsAttributesItem Name="SelectedNodesChanged" Type="EventCallback<IList<TNode>>">
        Occurs when the selected TreeView nodes are changed.
    </DocsAttributesItem>
    <DocsAttributesItem Name="AutoExpandAll" Type="bool" Default="false">
        Defines if the treenode should be automatically expanded. Note that it can happen only once when the tree is first loaded.
    </DocsAttributesItem>
    <DocsAttributesItem Name="ExpandedNodes" Type="List<TNode>">
        List of currently expanded TreeView items (child nodes).
    </DocsAttributesItem>
    <DocsAttributesItem Name="ExpandedNodeChanged" Type="EventCallback<TNode>">
        Occurs when the collection of expanded nodes has changed.
    </DocsAttributesItem>
    <DocsAttributesItem Name="GetChildNodes" Type="Func<TNode, IEnumerable<TNode>>">
        Expression that allows the child nodes to be identified for a particular node.
    </DocsAttributesItem>
    <DocsAttributesItem Name="HasChildNodes" Type="Func<TNode, bool>" Default="(node) => false">
        Expression that indicates whether the current node has any children nodes?
    </DocsAttributesItem>
    <DocsAttributesItem Name="IsDisabled" Type="Func<TNode, bool>" Default="(node) => false">
        Expression that indicates whether the current node should be disabled from selection
    </DocsAttributesItem>
    <DocsAttributesItem Name="GetChildNodesAsync" Type="Func<TNode, Task<IEnumerable<TNode>>>">
        Asynchronous expression that allows the child nodes to be identified for a particular node.
    </DocsAttributesItem>
    <DocsAttributesItem Name="HasChildNodesAsync" Type="Func<TNode, Task<bool>>" Default="null">
        Asynchronous expression that indicates whether the current node has any children nodes?
    </DocsAttributesItem>
    <DocsAttributesItem Name="ExpandIconName" Type="IconName" Default="ChevronRight">
        Defines the name of the treenode expand icon.
    </DocsAttributesItem>
    <DocsAttributesItem Name="ExpandIconStyle" Type="IconStyle?" Default="null">
        Defines the style of the treenode expand icon.
    </DocsAttributesItem>
    <DocsAttributesItem Name="ExpandIconSize" Type="IconSize?" Default="null">
        Defines the size of the treenode expand icon.
    </DocsAttributesItem>
    <DocsAttributesItem Name="CollapseIconName" Type="IconName" Default="ChevronRight">
        Defines the name of the treenode collapse icon.
    </DocsAttributesItem>
    <DocsAttributesItem Name="CollapseIconStyle" Type="IconStyle?" Default="null">
        Defines the style of the treenode collapse icon.
    </DocsAttributesItem>
    <DocsAttributesItem Name="CollapseIconSize" Type="IconSize?" Default="null">
        Defines the size of the treenode collapse icon.
    </DocsAttributesItem>
    <DocsAttributesItem Name="NodeContextMenu" Type="EventCallback<TreeViewNodeMouseEventArgs<TNode>>">
        The event is fired when the node is right clicked to show the context menu.
    </DocsAttributesItem>
    <DocsAttributesItem Name="NodeContextMenuPreventDefault" Type="bool" Default="false">
        Used to prevent the default action for a NodeContextMenu event.
    </DocsAttributesItem>
</DocsAttributes>

<Heading Size="HeadingSize.Is3">
    Methods
</Heading>

<DocsMethods>
    <DocsMethodsItem Name="ExpandAll()" ReturnType="Task">
        Expands all the collapsed TreeView nodes.
    </DocsMethodsItem>
    <DocsMethodsItem Name="CollapseAll()" ReturnType="Task">
        Collapses all the expanded TreeView nodes.
    </DocsMethodsItem>
    <DocsMethodsItem Name="ToggleCheckNode()" ReturnType="Task" Parameters="TNode node">
        Toggles the checked state of the node when in multiple selection mode.
    </DocsMethodsItem>
    <DocsMethodsItem Name="SelectNode()" ReturnType="void" Parameters="TNode node">
        Selects the node when in single selection mode.
    </DocsMethodsItem>
    <DocsMethodsItem Name="RemoveNode()" ReturnType="Task" Parameters="TNode node">
        Attempts to find and remove an existing node from the TreeView.
    </DocsMethodsItem>
    <DocsMethodsItem Name="Reload()" ReturnType="Task">
        Triggers the reload of the TreeView Nodes.
    </DocsMethodsItem>
</DocsMethods>